package com.sms.service;

import com.sms.exception.DataFileCorruptedException;
import com.sms.exception.SMSException;
import com.sms.model.Student;

import java.util.List;

/**
 * 学生管理服务接口
 * 位置：com.sms.service.StudentService
 */
public interface StudentService {
    /**
     * 添加学生信息
     * @param student 学生对象
     * @throws SMSException 当学号已存在或数据无效时抛出
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    void addStudent(Student student) throws SMSException, DataFileCorruptedException;
    
    /**
     * 删除学生信息
     * @param studentId 学号
     * @return true-删除成功, false-学生不存在
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    boolean deleteStudent(String studentId) throws DataFileCorruptedException;
    
    /**
     * 根据学号查询学生信息
     * @param studentId 学号
     * @return 学生对象，未找到时返回null
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    Student getStudent(String studentId) throws DataFileCorruptedException;
    
    /**
     * 获取所有学生列表
     * @return 学生列表（按学号排序）
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    List<Student> getAllStudents() throws DataFileCorruptedException;
    
    /**
     * 更新学生信息
     * @param student 学生对象（包含更新后的数据）
     * @return true-更新成功, false-学生不存在
     * @throws SMSException 当数据无效时抛出
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    boolean updateStudent(Student student) throws SMSException, DataFileCorruptedException;
    
    /**
     * 根据姓名搜索学生
     * @param name 姓名（支持模糊匹配）
     * @return 匹配的学生列表
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    List<Student> searchStudentsByName(String name) throws DataFileCorruptedException;
    
    /**
     * 根据班级查询学生
     * @param className 班级名称
     * @return 该班级的学生列表
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    List<Student> getStudentsByClass(String className) throws DataFileCorruptedException;

    
    /**
     * 批量添加学生
     * @param students 学生列表
     * @return 成功添加的学生数量
     * @throws SMSException 当学号重复或数据无效时抛出
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    int batchAddStudents(List<Student> students) throws SMSException, DataFileCorruptedException;
    
    /**
     * 获取学生总数
     * @return 学生数量
     * @throws DataFileCorruptedException 当数据文件损坏时抛出
     */
    int getStudentCount() throws DataFileCorruptedException;
}